patram 0.5.0 → 0.6.0

package/lib/parse-claims.js

@@ -5,7 +5,11 @@
 import { getFileExtension } from './claim-helpers.js';
 import { parseJsdocClaims } from './parse-jsdoc-claims.js';
 import { parseMarkdownClaims } from './parse-markdown-claims.js';
-import { MARKDOWN_SOURCE_FILE_EXTENSIONS } from './source-file-defaults.js';
+import { parseYamlClaims } from './parse-yaml-claims.js';
+import {
+  MARKDOWN_SOURCE_FILE_EXTENSIONS,
+  YAML_SOURCE_FILE_EXTENSIONS,
+} from './source-file-defaults.js';
 
 /**
  * Source claim dispatch.
@@ -26,21 +30,24 @@ import { MARKDOWN_SOURCE_FILE_EXTENSIONS } from './source-file-defaults.js';
  */
 
 const MARKDOWN_EXTENSIONS = new Set(MARKDOWN_SOURCE_FILE_EXTENSIONS);
+const YAML_EXTENSIONS = new Set(YAML_SOURCE_FILE_EXTENSIONS);
 
 /**
  * Parse one source file into claims and diagnostics.
  *
  * @param {ParseClaimsInput} parse_input
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
  * @returns {ParseSourceFileResult}
  */
-export function parseSourceFile(parse_input) {
+export function parseSourceFile(parse_input, parse_options) {
   const file_extension = getFileExtension(parse_input.path);
 
   if (MARKDOWN_EXTENSIONS.has(file_extension)) {
-    return {
-      claims: parseMarkdownClaims(parse_input),
-      diagnostics: [],
-    };
+    return parseMarkdownClaims(parse_input, parse_options);
+  }
+
+  if (YAML_EXTENSIONS.has(file_extension)) {
+    return parseYamlClaims(parse_input, parse_options);
   }
 
   return parseJsdocClaims(parse_input);
@@ -50,8 +57,88 @@ export function parseSourceFile(parse_input) {
  * Parse a file into neutral Patram claims.
  *
  * @param {ParseClaimsInput} parse_input
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
  * @returns {PatramClaim[]}
  */
-export function parseClaims(parse_input) {
-  return parseSourceFile(parse_input).claims;
+export function parseClaims(parse_input, parse_options) {
+  return parseSourceFile(parse_input, parse_options).claims;
+}
+
+/**
+ * Build parser options from repo config.
+ *
+ * @param {{ fields?: Record<string, { multiple?: boolean }>, mappings?: Record<string, { emit?: unknown, node?: unknown }> } | undefined} repo_config
+ * @returns {{ multi_value_directive_names: Set<string> }}
+ */
+export function createParseOptions(repo_config) {
+  return {
+    multi_value_directive_names: collectMultiValueDirectiveNames(repo_config),
+  };
+}
+
+/**
+ * @param {{ fields?: Record<string, { multiple?: boolean }>, mappings?: Record<string, { emit?: unknown, node?: unknown }> } | undefined} repo_config
+ * @returns {Set<string>}
+ */
+function collectMultiValueDirectiveNames(repo_config) {
+  /** @type {Set<string>} */
+  const multi_value_directive_names = new Set();
+
+  collectMultipleFieldNames(repo_config?.fields, multi_value_directive_names);
+  collectEmitOnlyDirectiveNames(
+    repo_config?.mappings,
+    multi_value_directive_names,
+  );
+
+  return multi_value_directive_names;
+}
+
+/**
+ * @param {Record<string, { multiple?: boolean }> | undefined} fields
+ * @param {Set<string>} multi_value_directive_names
+ */
+function collectMultipleFieldNames(fields, multi_value_directive_names) {
+  for (const [field_name, field_definition] of Object.entries(fields ?? {})) {
+    if (field_definition.multiple === true) {
+      multi_value_directive_names.add(field_name);
+    }
+  }
+}
+
+/**
+ * @param {Record<string, { emit?: unknown, node?: unknown }> | undefined} mappings
+ * @param {Set<string>} multi_value_directive_names
+ */
+function collectEmitOnlyDirectiveNames(mappings, multi_value_directive_names) {
+  for (const [mapping_name, mapping_definition] of Object.entries(
+    mappings ?? {},
+  )) {
+    const directive_name = resolveEmitOnlyDirectiveName(
+      mapping_name,
+      mapping_definition,
+    );
+
+    if (directive_name) {
+      multi_value_directive_names.add(directive_name);
+    }
+  }
+}
+
+/**
+ * @param {string} mapping_name
+ * @param {{ emit?: unknown, node?: unknown }} mapping_definition
+ * @returns {string | null}
+ */
+function resolveEmitOnlyDirectiveName(mapping_name, mapping_definition) {
+  const directive_match = mapping_name.match(/^[^.]+\.directive\.(.+)$/du);
+
+  if (
+    !directive_match ||
+    mapping_definition.emit === undefined ||
+    mapping_definition.node !== undefined
+  ) {
+    return null;
+  }
+
+  return directive_match[1];
 }

package/lib/parse-claims.types.ts

@@ -1,5 +1,11 @@
 import type { PatramDiagnostic } from './load-patram-config.types.ts';
 
+export type MarkdownDirectiveStyle =
+  | 'front_matter'
+  | 'visible_line'
+  | 'list_item'
+  | 'hidden_tag';
+
 export interface ParseClaimsInput {
   path: string;
   source: string;
@@ -14,6 +20,7 @@ export interface ClaimOrigin {
 export interface PatramClaim {
   document_id: string;
   id: string;
+  markdown_style?: MarkdownDirectiveStyle;
   name?: string;
   origin: ClaimOrigin;
   parser?: string;

package/lib/parse-markdown-claims.js

@@ -1,5 +1,6 @@
 /**
  * @import { PatramClaim, ParseClaimsInput, PatramClaimFields } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
  */
 
 import { createClaim, isPathLikeTarget } from './claim-helpers.js';
@@ -31,9 +32,10 @@ const MARKDOWN_LINK_PATTERN = /\[([^\]]+)\]\(([^)]+)\)/dgu;
 
 /**
  * @param {ParseClaimsInput} parse_input
- * @returns {PatramClaim[]}
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
+ * @returns {{ claims: PatramClaim[], diagnostics: PatramDiagnostic[] }}
  */
-export function parseMarkdownClaims(parse_input) {
+export function parseMarkdownClaims(parse_input, parse_options) {
   const lines = parse_input.source.split('\n');
 
   /** @type {PatramClaim[]} */
@@ -41,6 +43,7 @@ export function parseMarkdownClaims(parse_input) {
   const front_matter_result = parseFrontMatterDirectiveFields(
     parse_input.path,
     lines,
+    parse_options,
   );
   /** @type {{ character: string, length: number } | null} */
   let open_fence = null;
@@ -93,7 +96,10 @@ export function parseMarkdownClaims(parse_input) {
     collectHiddenDirectiveClaims(parse_input.path, line, line_number, claims);
   }
 
-  return claims;
+  return {
+    claims,
+    diagnostics: front_matter_result.diagnostics,
+  };
 }
 
 /**

package/lib/parse-markdown-directives.js

@@ -1,22 +1,31 @@
 /**
- * @import { PatramClaimFields } from './parse-claims.types.ts';
+ * @import { MarkdownDirectiveStyle, PatramClaimFields } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
  */
 
+import { parseYamlDirectiveFields } from './parse-yaml-claims.js';
+
 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;
+const LIST_ITEM_DIRECTIVE_PATTERN = /^-\s+([A-Z][A-Za-z _-]*):\s+(.+)$/du;
+const VISIBLE_DIRECTIVE_PATTERN = /^([A-Z][A-Za-z _-]*):\s+(.+)$/du;
 
 /**
  * @param {string} file_path
  * @param {string[]} lines
- * @returns {{ body_start: number, directive_fields: PatramClaimFields[] }}
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
+ * @returns {{ body_start: number, diagnostics: PatramDiagnostic[], directive_fields: PatramClaimFields[] }}
  */
-export function parseFrontMatterDirectiveFields(file_path, lines) {
+export function parseFrontMatterDirectiveFields(
+  file_path,
+  lines,
+  parse_options,
+) {
   if (lines[0] !== '---') {
     return {
       body_start: 0,
+      diagnostics: [],
       directive_fields: [],
     };
   }
@@ -26,31 +35,23 @@ export function parseFrontMatterDirectiveFields(file_path, lines) {
   if (closing_line_index < 0) {
     return {
       body_start: 0,
+      diagnostics: [],
       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);
-  }
+  const parse_result = parseYamlDirectiveFields({
+    file_path,
+    markdown_style: 'front_matter',
+    multi_value_directive_names: parse_options?.multi_value_directive_names,
+    parser: 'markdown',
+    source_text: lines.slice(1, closing_line_index).join('\n'),
+    start_line: 2,
+  });
 
   return {
     body_start: closing_line_index + 1,
-    directive_fields,
+    diagnostics: parse_result.diagnostics,
+    directive_fields: parse_result.directive_fields,
   };
 }
 
@@ -61,8 +62,21 @@ export function parseFrontMatterDirectiveFields(file_path, lines) {
  * @returns {PatramClaimFields | null}
  */
 export function matchVisibleDirectiveFields(file_path, line, line_number) {
+  const list_item_match = matchDirectiveFields(
+    LIST_ITEM_DIRECTIVE_PATTERN,
+    'list_item',
+    file_path,
+    line,
+    line_number,
+  );
+
+  if (list_item_match) {
+    return list_item_match;
+  }
+
   return matchDirectiveFields(
     VISIBLE_DIRECTIVE_PATTERN,
+    'visible_line',
     file_path,
     line,
     line_number,
@@ -78,6 +92,7 @@ export function matchVisibleDirectiveFields(file_path, line, line_number) {
 export function matchHiddenDirectiveFields(file_path, line, line_number) {
   return matchDirectiveFields(
     MARKDOWN_HIDDEN_DIRECTIVE_PATTERN,
+    'hidden_tag',
     file_path,
     line,
     line_number,
@@ -100,12 +115,19 @@ function findFrontMatterClosingLineIndex(lines) {
 
 /**
  * @param {RegExp} pattern
+ * @param {MarkdownDirectiveStyle} markdown_style
  * @param {string} file_path
  * @param {string} line
  * @param {number} line_number
  * @returns {PatramClaimFields | null}
  */
-function matchDirectiveFields(pattern, file_path, line, line_number) {
+function matchDirectiveFields(
+  pattern,
+  markdown_style,
+  file_path,
+  line,
+  line_number,
+) {
   const directive_match = line.match(pattern);
 
   if (!directive_match) {
@@ -113,6 +135,7 @@ function matchDirectiveFields(pattern, file_path, line, line_number) {
   }
 
   return {
+    markdown_style,
     name: normalizeDirectiveName(directive_match[1]),
     origin: {
       column: 1,