patram 0.11.0 → 0.12.0

package/lib/parse/markdown/parse-markdown-claims.js

@@ -5,8 +5,12 @@
 
 import { createClaim, isPathLikeTarget } from '../claim-helpers.js';
 import {
+  getMarkdownDescription,
+  getMarkdownTitle,
+} from './parse-markdown-prose.js';
+import {
+  collectVisibleDirectiveFields,
   matchHiddenDirectiveFields,
-  matchVisibleDirectiveFields,
   parseFrontMatterDirectiveFields,
 } from './parse-markdown-directives.js';
 
@@ -16,17 +20,16 @@ import {
  * 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
+ * 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;
 
@@ -37,30 +40,19 @@ const MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/dgu;
  */
 export function parseMarkdownClaims(parse_input, parse_options) {
   const lines = parse_input.source.split('\n');
-
-  /** @type {PatramClaim[]} */
-  const claims = [];
   const front_matter_result = parseFrontMatterDirectiveFields(
     parse_input.path,
     lines,
     parse_options,
   );
+  /** @type {PatramClaim[]} */
+  const claims = collectMarkdownMetadataClaims(
+    parse_input.path,
+    lines,
+    front_matter_result.body_start,
+  );
   /** @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(
@@ -70,11 +62,12 @@ export function parseMarkdownClaims(parse_input, parse_options) {
     );
   }
 
-  for (const [line_index, line] of lines.entries()) {
+  for (let line_index = 0; line_index < lines.length; line_index += 1) {
     if (line_index < front_matter_result.body_start) {
       continue;
     }
 
+    const line = lines[line_index];
     const line_number = line_index + 1;
 
     if (open_fence) {
@@ -92,7 +85,19 @@ export function parseMarkdownClaims(parse_input, parse_options) {
     }
 
     collectMarkdownLinkClaims(parse_input.path, line, line_number, claims);
-    collectVisibleDirectiveClaims(parse_input.path, line, line_number, claims);
+
+    const next_line_index = collectVisibleDirectiveClaims(
+      parse_input.path,
+      lines,
+      line_index,
+      claims,
+    );
+
+    if (next_line_index !== null) {
+      line_index = next_line_index - 1;
+      continue;
+    }
+
     collectHiddenDirectiveClaims(parse_input.path, line, line_number, claims);
   }
 
@@ -102,6 +107,34 @@ export function parseMarkdownClaims(parse_input, parse_options) {
   };
 }
 
+/**
+ * @param {string} file_path
+ * @param {string[]} lines
+ * @param {number} start_line_index
+ * @returns {PatramClaim[]}
+ */
+function collectMarkdownMetadataClaims(file_path, lines, start_line_index) {
+  /** @type {PatramClaim[]} */
+  const claims = [];
+  const title_result = getMarkdownTitle(lines, start_line_index);
+
+  if (title_result) {
+    claims.push(createDocumentTitleClaim(file_path, title_result));
+  }
+
+  const description_result = getMarkdownDescription(
+    file_path,
+    lines,
+    title_result,
+  );
+
+  if (description_result) {
+    claims.push(createDocumentDescriptionClaim(file_path, description_result));
+  }
+
+  return claims;
+}
+
 /**
  * @param {string} file_path
  * @param {string} line
@@ -138,20 +171,25 @@ function collectMarkdownLinkClaims(file_path, line, line_number, claims) {
 
 /**
  * @param {string} file_path
- * @param {string} line
- * @param {number} line_number
+ * @param {string[]} lines
+ * @param {number} line_index
  * @param {PatramClaim[]} claims
+ * @returns {number | null}
  */
-function collectVisibleDirectiveClaims(file_path, line, line_number, claims) {
-  const directive_fields = matchVisibleDirectiveFields(
+function collectVisibleDirectiveClaims(file_path, lines, line_index, claims) {
+  const directive_result = collectVisibleDirectiveFields(
     file_path,
-    line,
-    line_number,
+    lines,
+    line_index,
   );
 
-  if (directive_fields) {
-    pushDirectiveClaim(file_path, claims, directive_fields);
+  if (!directive_result) {
+    return null;
   }
+
+  pushDirectiveClaim(file_path, claims, directive_result.directive_fields);
+
+  return directive_result.next_line_index;
 }
 
 /**
@@ -173,36 +211,35 @@ function collectHiddenDirectiveClaims(file_path, line, line_number, claims) {
 }
 
 /**
- * @param {string[]} lines
- * @param {number} start_line_index
- * @returns {{ line: number, value: string } | null}
+ * @param {string} file_path
+ * @param {{ line: number, value: string }} title_result
+ * @returns {PatramClaim}
  */
-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(),
-    };
-  }
+function createDocumentTitleClaim(file_path, title_result) {
+  return createClaim(file_path, 1, 'document.title', {
+    origin: {
+      column: 1,
+      line: title_result.line,
+      path: file_path,
+    },
+    value: title_result.value,
+  });
+}
 
-  return {
-    line: start_line_index + 1,
-    value: trimmed_line,
-  };
+/**
+ * @param {string} file_path
+ * @param {{ column: number, line: number, value: string }} description_result
+ * @returns {PatramClaim}
+ */
+function createDocumentDescriptionClaim(file_path, description_result) {
+  return createClaim(file_path, 2, 'document.description', {
+    origin: {
+      column: description_result.column,
+      line: description_result.line,
+      path: file_path,
+    },
+    value: description_result.value,
+  });
 }
 
 /**

package/lib/parse/markdown/parse-markdown-directives.d.ts

@@ -20,15 +20,19 @@ export function parseFrontMatterDirectiveFields(file_path: string, lines: string
 export function matchVisibleDirectiveFields(file_path: string, line: string, line_number: number): PatramClaimFields | null;
 /**
  * @param {string} file_path
- * @param {string} line
- * @param {number} line_number
- * @returns {PatramClaimFields | null}
+ * @param {string[]} lines
+ * @param {number} line_index
+ * @returns {{ directive_fields: PatramClaimFields, next_line_index: number } | null}
  */
-export function matchHiddenDirectiveFields(file_path: string, line: string, line_number: number): PatramClaimFields | null;
+export function collectVisibleDirectiveFields(file_path: string, lines: string[], line_index: number): {
+    directive_fields: PatramClaimFields;
+    next_line_index: number;
+} | null;
 /**
  * @param {string} directive_label
- * @returns {string}
+ * @returns {string | null}
  */
-export function normalizeDirectiveName(directive_label: string): string;
+export function normalizeDirectiveName(directive_label: string): string | null;
+export function matchHiddenDirectiveFields(...args: unknown[]): PatramClaimFields | null;
 import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';
 import type { PatramClaimFields } from '../parse-claims.types.d.ts';

package/lib/parse/markdown/parse-markdown-directives.js

@@ -6,10 +6,16 @@
 import { parseYamlDirectiveFields } from '../yaml/parse-yaml-claims.js';
 
 const FRONT_MATTER_BOUNDARY_PATTERN = /^---$/du;
-const MARKDOWN_HIDDEN_DIRECTIVE_PATTERN =
-  /^\[patram\s+([A-Za-z][A-Za-z0-9 _-]*)=(.+)\]:\s*#\s*$/du;
-const LIST_ITEM_DIRECTIVE_PATTERN = /^-\s+([A-Z][A-Za-z _-]*):\s+(.+)$/du;
-const VISIBLE_DIRECTIVE_PATTERN = /^([A-Z][A-Za-z _-]*):\s+(.+)$/du;
+const FIELD_NAME_PATTERN = '[a-z][a-z0-9_]*';
+const LIST_ITEM_DIRECTIVE_PATTERN = new RegExp(
+  `^-\\s+(${FIELD_NAME_PATTERN}):\\s+(.+)$`,
+  'du',
+);
+const LIST_ITEM_DIRECTIVE_CONTINUATION_PATTERN = /^ {2,3}\S/u;
+const VISIBLE_DIRECTIVE_PATTERN = new RegExp(
+  `^(${FIELD_NAME_PATTERN}):\\s+(.+)$`,
+  'du',
+);
 
 /**
  * @param {string} file_path
@@ -85,20 +91,68 @@ export function matchVisibleDirectiveFields(file_path, line, line_number) {
 
 /**
  * @param {string} file_path
- * @param {string} line
- * @param {number} line_number
- * @returns {PatramClaimFields | null}
+ * @param {string[]} lines
+ * @param {number} line_index
+ * @returns {{ directive_fields: PatramClaimFields, next_line_index: number } | null}
  */
-export function matchHiddenDirectiveFields(file_path, line, line_number) {
-  return matchDirectiveFields(
-    MARKDOWN_HIDDEN_DIRECTIVE_PATTERN,
-    'hidden_tag',
+export function collectVisibleDirectiveFields(file_path, lines, line_index) {
+  const line = lines[line_index];
+
+  if (line === undefined) {
+    return null;
+  }
+
+  const directive_fields = matchVisibleDirectiveFields(
     file_path,
     line,
-    line_number,
+    line_index + 1,
   );
+
+  if (!directive_fields) {
+    return null;
+  }
+
+  if (directive_fields.markdown_style !== 'list_item') {
+    return {
+      directive_fields,
+      next_line_index: line_index + 1,
+    };
+  }
+
+  const continuation_result = collectListItemDirectiveContinuation(
+    lines,
+    line_index + 1,
+  );
+  const directive_value = directive_fields.value;
+
+  if (
+    continuation_result.value.length === 0 ||
+    typeof directive_value !== 'string'
+  ) {
+    return {
+      directive_fields,
+      next_line_index: continuation_result.next_line_index,
+    };
+  }
+
+  return {
+    directive_fields: {
+      ...directive_fields,
+      value: `${directive_value} ${continuation_result.value}`,
+    },
+    next_line_index: continuation_result.next_line_index,
+  };
 }
 
+/**
+ * @param {...unknown} args
+ * @returns {PatramClaimFields | null}
+ */
+export const matchHiddenDirectiveFields = (...args) => {
+  void args;
+  return null;
+};
+
 /**
  * @param {string[]} lines
  * @returns {number}
@@ -134,9 +188,15 @@ function matchDirectiveFields(
     return null;
   }
 
+  const directive_name = normalizeDirectiveName(directive_match[1]);
+
+  if (!directive_name) {
+    return null;
+  }
+
   return {
     markdown_style,
-    name: normalizeDirectiveName(directive_match[1]),
+    name: directive_name,
     origin: {
       column: 1,
       line: line_number,
@@ -147,13 +207,39 @@ function matchDirectiveFields(
   };
 }
 
+/**
+ * @param {string[]} lines
+ * @param {number} line_index
+ * @returns {{ next_line_index: number, value: string }}
+ */
+function collectListItemDirectiveContinuation(lines, line_index) {
+  /** @type {string[]} */
+  const continuation_lines = [];
+  let next_line_index = line_index;
+
+  while (next_line_index < lines.length) {
+    const line = lines[next_line_index];
+
+    if (!LIST_ITEM_DIRECTIVE_CONTINUATION_PATTERN.test(line)) {
+      break;
+    }
+
+    continuation_lines.push(line.trim());
+    next_line_index += 1;
+  }
+
+  return {
+    next_line_index,
+    value: continuation_lines.join(' '),
+  };
+}
+
 /**
  * @param {string} directive_label
- * @returns {string}
+ * @returns {string | null}
  */
 export function normalizeDirectiveName(directive_label) {
-  return directive_label
-    .trim()
-    .toLowerCase()
-    .replaceAll(/[\s-]+/dgu, '_');
+  const normalized_name = directive_label.trim();
+
+  return /^[a-z][a-z0-9_]*$/du.test(normalized_name) ? normalized_name : null;
 }

package/lib/parse/markdown/parse-markdown-prose.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @param {string[]} lines
+ * @param {number} start_line_index
+ * @returns {{ is_heading: boolean, line: number, line_index: number, value: string } | null}
+ */
+export function getMarkdownTitle(lines: string[], start_line_index: number): {
+    is_heading: boolean;
+    line: number;
+    line_index: number;
+    value: string;
+} | null;
+/**
+ * @param {string} file_path
+ * @param {string[]} lines
+ * @param {{ is_heading: boolean, line: number, line_index: number, value: string } | null} title_result
+ * @returns {{ column: number, line: number, value: string } | null}
+ */
+export function getMarkdownDescription(file_path: string, lines: string[], title_result: {
+    is_heading: boolean;
+    line: number;
+    line_index: number;
+    value: string;
+} | null): {
+    column: number;
+    line: number;
+    value: string;
+} | null;

package/lib/parse/markdown/parse-markdown-prose.js

@@ -0,0 +1,243 @@
+import {
+  collectVisibleDirectiveFields,
+  matchHiddenDirectiveFields,
+} from './parse-markdown-directives.js';
+
+const HEADING_PATTERN = /^#{1,6}\s+(.+)$/du;
+const BLOCKQUOTE_PATTERN = /^\s*>/u;
+const INDENTED_CODE_PATTERN = /^(?: {4}|\t)\S/u;
+const MARKDOWN_DESCRIPTION_SENTENCE_PATTERN = /^(.+?[.!?])(?:\s+|$)[\s\S]*$/du;
+const MARKDOWN_DESCRIPTION_LENGTH_LIMIT = 120;
+const MARKDOWN_FENCE_PATTERN = /^([`~]{3,})/du;
+const MARKDOWN_ORDERED_LIST_PATTERN = /^\s*\d+[.)]\s+/u;
+const MARKDOWN_TABLE_PATTERN = /^\s*\|/u;
+const MARKDOWN_UNORDERED_LIST_PATTERN = /^\s*[-+*]\s+/u;
+
+/**
+ * @param {string[]} lines
+ * @param {number} start_line_index
+ * @returns {{ is_heading: boolean, line: number, line_index: number, value: string } | null}
+ */
+export function getMarkdownTitle(lines, start_line_index) {
+  const first_line_index = skipBlankLines(lines, start_line_index);
+  const first_line = lines[first_line_index];
+
+  if (first_line === undefined) {
+    return null;
+  }
+
+  const trimmed_line = first_line.trim();
+  const heading_match = trimmed_line.match(HEADING_PATTERN);
+
+  if (heading_match) {
+    return {
+      is_heading: true,
+      line: first_line_index + 1,
+      line_index: first_line_index,
+      value: heading_match[1].trim(),
+    };
+  }
+
+  return {
+    is_heading: false,
+    line: first_line_index + 1,
+    line_index: first_line_index,
+    value: trimmed_line,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {string[]} lines
+ * @param {{ is_heading: boolean, line: number, line_index: number, value: string } | null} title_result
+ * @returns {{ column: number, line: number, value: string } | null}
+ */
+export function getMarkdownDescription(file_path, lines, title_result) {
+  if (!title_result) {
+    return null;
+  }
+
+  let line_index = title_result.is_heading
+    ? title_result.line_index + 1
+    : title_result.line_index;
+
+  line_index = skipBlankLines(lines, line_index);
+
+  if (line_index >= lines.length) {
+    return null;
+  }
+
+  if (
+    title_result.is_heading &&
+    isMarkdownDirectiveLine(file_path, lines, line_index)
+  ) {
+    line_index = skipMarkdownDirectiveBlock(file_path, lines, line_index);
+    line_index = skipBlankLines(lines, line_index);
+  }
+
+  const paragraph_result = collectMarkdownParagraph(lines, line_index);
+
+  if (!paragraph_result) {
+    return null;
+  }
+
+  return {
+    column: paragraph_result.column,
+    line: paragraph_result.line,
+    value: summarizeMarkdownParagraph(paragraph_result.value),
+  };
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} line_index
+ * @returns {{ column: number, line: number, value: string } | null}
+ */
+function collectMarkdownParagraph(lines, line_index) {
+  const first_line = lines[line_index];
+
+  if (first_line === undefined || !isMarkdownParagraphLine(first_line)) {
+    return null;
+  }
+
+  const paragraph_lines = [first_line.trim()];
+  let next_line_index = line_index + 1;
+
+  while (next_line_index < lines.length) {
+    const next_line = lines[next_line_index];
+
+    if (next_line.trim().length === 0 || !isMarkdownParagraphLine(next_line)) {
+      break;
+    }
+
+    paragraph_lines.push(next_line.trim());
+    next_line_index += 1;
+  }
+
+  return {
+    column: getLineColumn(first_line),
+    line: line_index + 1,
+    value: paragraph_lines.join(' '),
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {string[]} lines
+ * @param {number} line_index
+ * @returns {boolean}
+ */
+function isMarkdownDirectiveLine(file_path, lines, line_index) {
+  return (
+    collectVisibleDirectiveFields(file_path, lines, line_index) !== null ||
+    matchHiddenDirectiveFields(file_path, lines[line_index], line_index + 1) !==
+      null
+  );
+}
+
+/**
+ * @param {string} file_path
+ * @param {string[]} lines
+ * @param {number} line_index
+ * @returns {number}
+ */
+function skipMarkdownDirectiveBlock(file_path, lines, line_index) {
+  let next_line_index = line_index;
+
+  while (next_line_index < lines.length) {
+    const line = lines[next_line_index];
+
+    if (line.trim().length === 0) {
+      next_line_index += 1;
+      continue;
+    }
+
+    const visible_directive_result = collectVisibleDirectiveFields(
+      file_path,
+      lines,
+      next_line_index,
+    );
+
+    if (visible_directive_result) {
+      next_line_index = visible_directive_result.next_line_index;
+      continue;
+    }
+
+    if (
+      matchHiddenDirectiveFields(file_path, line, next_line_index + 1) === null
+    ) {
+      break;
+    }
+
+    next_line_index += 1;
+  }
+
+  return next_line_index;
+}
+
+/**
+ * @param {string} line
+ * @returns {number}
+ */
+function getLineColumn(line) {
+  const first_character_index = line.search(/\S/u);
+
+  return first_character_index < 0 ? 1 : first_character_index + 1;
+}
+
+/**
+ * @param {string} paragraph_text
+ * @returns {string}
+ */
+function summarizeMarkdownParagraph(paragraph_text) {
+  if (paragraph_text.length <= MARKDOWN_DESCRIPTION_LENGTH_LIMIT) {
+    return paragraph_text;
+  }
+
+  const sentence_match = paragraph_text.match(
+    MARKDOWN_DESCRIPTION_SENTENCE_PATTERN,
+  );
+
+  if (!sentence_match) {
+    return paragraph_text;
+  }
+
+  return sentence_match[1].trim();
+}
+
+/**
+ * @param {string} line
+ * @returns {boolean}
+ */
+function isMarkdownParagraphLine(line) {
+  const trimmed_line = line.trim();
+
+  if (trimmed_line.length === 0) {
+    return false;
+  }
+
+  return !(
+    HEADING_PATTERN.test(trimmed_line) ||
+    MARKDOWN_FENCE_PATTERN.test(trimmed_line) ||
+    MARKDOWN_ORDERED_LIST_PATTERN.test(line) ||
+    MARKDOWN_TABLE_PATTERN.test(line) ||
+    MARKDOWN_UNORDERED_LIST_PATTERN.test(line) ||
+    BLOCKQUOTE_PATTERN.test(line) ||
+    INDENTED_CODE_PATTERN.test(line)
+  );
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} start_line_index
+ * @returns {number}
+ */
+function skipBlankLines(lines, start_line_index) {
+  let line_index = start_line_index;
+
+  while (line_index < lines.length && lines[line_index].trim().length === 0) {
+    line_index += 1;
+  }
+
+  return line_index;
+}