patram 0.4.0 → 0.6.0

package/lib/load-patram-config.types.ts

@@ -1,158 +1,56 @@
-import type {
-  ClassDefinition,
-  MappingDefinition,
-  RelationDefinition,
-} from './patram-config.types.ts';
-
-export interface StoredQueryConfig {
-  where: string;
-}
-
+export type StoredQueryConfig =
+  import('./load-patram-config.js').StoredQueryConfig;
+export type FieldDisplayConfig =
+  import('./load-patram-config.js').FieldDisplayConfig;
+export type FieldQueryConfig =
+  import('./load-patram-config.js').FieldQueryConfig;
 export type FieldValueTypeName =
-  | 'string'
-  | 'integer'
-  | 'enum'
-  | 'path'
-  | 'glob'
-  | 'date'
-  | 'date_time';
-
-export interface FieldDisplayConfig {
-  hidden?: boolean;
-  order?: number;
-}
-
-export interface FieldQueryConfig {
-  contains?: boolean;
-  prefix?: boolean;
-}
-
-export interface StringFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  query?: FieldQueryConfig;
-  type: 'string';
-}
-
-export interface IntegerFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'integer';
-}
-
-export interface EnumFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'enum';
-  values: string[];
-}
-
-export interface PathFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  path_class?: string;
-  type: 'path';
-}
-
-export interface GlobFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'glob';
-}
-
-export interface DateFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'date';
-}
-
-export interface DateTimeFieldConfig {
-  display?: FieldDisplayConfig;
-  multiple?: boolean;
-  type: 'date_time';
-}
-
+  import('./load-patram-config.js').MetadataFieldConfig['type'];
 export type MetadataFieldConfig =
-  | DateFieldConfig
-  | DateTimeFieldConfig
-  | EnumFieldConfig
-  | GlobFieldConfig
-  | IntegerFieldConfig
-  | PathFieldConfig
-  | StringFieldConfig;
-
-export interface ClassFieldRuleConfig {
-  presence: 'required' | 'optional' | 'forbidden';
-}
-
+  import('./load-patram-config.js').MetadataFieldConfig;
+export type StringFieldConfig = Extract<
+  MetadataFieldConfig,
+  { type: 'string' }
+>;
+export type IntegerFieldConfig = Extract<
+  MetadataFieldConfig,
+  { type: 'integer' }
+>;
+export type EnumFieldConfig = Extract<MetadataFieldConfig, { type: 'enum' }>;
+export type PathFieldConfig = Extract<MetadataFieldConfig, { type: 'path' }>;
+export type GlobFieldConfig = Extract<MetadataFieldConfig, { type: 'glob' }>;
+export type DateFieldConfig = Extract<MetadataFieldConfig, { type: 'date' }>;
+export type DateTimeFieldConfig = Extract<
+  MetadataFieldConfig,
+  { type: 'date_time' }
+>;
+export type ClassFieldRuleConfig =
+  import('./load-patram-config.js').ClassFieldRuleConfig;
 export type DirectiveTypeConfig = MetadataFieldConfig;
 export type MetadataDirectiveRuleConfig = ClassFieldRuleConfig;
-
-export interface ClassSchemaConfig {
-  document_path_class?: string;
-  fields: Record<string, ClassFieldRuleConfig>;
-  unknown_fields?: 'ignore' | 'error';
-}
-
+export type ClassSchemaConfig =
+  import('./load-patram-config.js').ClassSchemaConfig;
 export type MetadataSchemaConfig = ClassSchemaConfig;
-
-export interface PathClassConfig {
-  prefixes: string[];
-}
-
-export type DerivedSummaryScalar = boolean | number | string | null;
-
-export interface DerivedSummaryCountFieldConfig {
-  count: {
-    traversal: string;
-    where: string;
-  };
-  name: string;
-}
-
-export interface DerivedSummarySelectCaseConfig {
-  value: DerivedSummaryScalar;
-  when: string;
-}
-
-export interface DerivedSummarySelectFieldConfig {
-  default: DerivedSummaryScalar;
-  name: string;
-  select: DerivedSummarySelectCaseConfig[];
-}
-
+export type PathClassConfig = import('./load-patram-config.js').PathClassConfig;
+export type DerivedSummaryScalar =
+  import('./load-patram-config.js').DerivedSummaryScalar;
+export type DerivedSummarySelectCaseConfig =
+  import('./load-patram-config.js').DerivedSummarySelectCaseConfig;
 export type DerivedSummaryFieldConfig =
-  | DerivedSummaryCountFieldConfig
-  | DerivedSummarySelectFieldConfig;
-
-export interface DerivedSummaryConfig {
-  classes: string[];
-  fields: DerivedSummaryFieldConfig[];
-}
-
-export interface PatramRepoConfig {
-  class_schemas?: Record<string, ClassSchemaConfig>;
-  classes?: Record<string, ClassDefinition>;
-  derived_summaries?: Record<string, DerivedSummaryConfig>;
-  fields?: Record<string, MetadataFieldConfig>;
-  include: string[];
-  mappings?: Record<string, MappingDefinition>;
-  path_classes?: Record<string, PathClassConfig>;
-  queries: Record<string, StoredQueryConfig>;
-  relations?: Record<string, RelationDefinition>;
-}
-
-export interface PatramDiagnostic {
-  code: string;
-  column: number;
-  level: 'error';
-  line: number;
-  message: string;
-  path: string;
-}
-
-export interface LoadPatramConfigResult {
-  config: PatramRepoConfig | null;
-  config_path: string;
-  diagnostics: PatramDiagnostic[];
-}
+  import('./load-patram-config.js').DerivedSummaryFieldConfig;
+export type DerivedSummaryCountFieldConfig = Extract<
+  DerivedSummaryFieldConfig,
+  { count: unknown }
+>;
+export type DerivedSummarySelectFieldConfig = Extract<
+  DerivedSummaryFieldConfig,
+  { select: unknown }
+>;
+export type DerivedSummaryConfig =
+  import('./load-patram-config.js').DerivedSummaryConfig;
+export type PatramRepoConfig =
+  import('./load-patram-config.js').PatramRepoConfig;
+export type PatramDiagnostic =
+  import('./load-patram-config.js').PatramDiagnostic;
+export type LoadPatramConfigResult =
+  import('./load-patram-config.js').LoadPatramConfigResult;

package/lib/load-project-graph.js

@@ -10,7 +10,7 @@ import { resolve } from 'node:path';
 import { buildGraph } from './build-graph.js';
 import { listSourceFiles } from './list-source-files.js';
 import { loadPatramConfig } from './load-patram-config.js';
-import { parseSourceFile } from './parse-claims.js';
+import { createParseOptions, parseSourceFile } from './parse-claims.js';
 import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
 
 /**
@@ -68,6 +68,7 @@ export async function loadProjectGraph(project_directory) {
     project_directory,
   );
   const collect_result = await collectClaims(
+    repo_config,
     source_file_paths,
     project_directory,
   );
@@ -96,25 +97,34 @@ export async function loadProjectGraph(project_directory) {
 }
 
 /**
+ * @param {PatramRepoConfig} repo_config
  * @param {string[]} source_file_paths
  * @param {string} project_directory
  * @returns {Promise<{ claims: PatramClaim[], diagnostics: PatramDiagnostic[] }>}
  */
-async function collectClaims(source_file_paths, project_directory) {
+async function collectClaims(
+  repo_config,
+  source_file_paths,
+  project_directory,
+) {
   /** @type {PatramClaim[]} */
   const claims = [];
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
+  const parse_options = createParseOptions(repo_config);
 
   for (const source_file_path of source_file_paths) {
     const source_text = await readFile(
       resolve(project_directory, source_file_path),
       'utf8',
     );
-    const parse_result = parseSourceFile({
-      path: source_file_path,
-      source: source_text,
-    });
+    const parse_result = parseSourceFile(
+      {
+        path: source_file_path,
+        source: source_text,
+      },
+      parse_options,
+    );
 
     claims.push(...parse_result.claims);
     diagnostics.push(...parse_result.diagnostics);

package/lib/parse-claims.js

@@ -1,12 +1,15 @@
-/** @import * as $k$$l$parse$j$claims$k$types$k$ts from './parse-claims.types.ts'; */
 /**
- * @import { ParseClaimsInput, ParseSourceFileResult } from './parse-claims.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaim } from './parse-claims.types.ts';
  */
 
 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.
@@ -27,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);
@@ -51,8 +57,88 @@ export function parseSourceFile(parse_input) {
  * Parse a file into neutral Patram claims.
  *
  * @param {ParseClaimsInput} parse_input
- * @returns {$k$$l$parse$j$claims$k$types$k$ts.PatramClaim[]}
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
+ * @returns {PatramClaim[]}
+ */
+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>}
  */
-export function parseClaims(parse_input) {
-  return parseSourceFile(parse_input).claims;
+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-jsdoc-claims.js

@@ -1,6 +1,6 @@
-/** @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 { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaimFields } from './parse-claims.types.ts';
  */
 
 import {
@@ -266,7 +266,7 @@ function compareClaimEntries(left_entry, right_entry) {
 /**
  * @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}
+ * @returns {PatramDiagnostic}
  */
 function createMultiplePatramBlocksDiagnostic(file_path, jsdoc_block) {
   return {

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,